Graphical user interfaces of modern workstations are usually composed of a number of items such as buttons, check boxes, text fields and scroll bars which allow a user to interactively communicate with the computer. We call a panel of such items a dialog.
This guide describes the use of dialogs in the Oberon System. Dialogs extend the original user interface of Oberon and give the user a choice between a compact textual interface (for professional programmers) and a more intuitive graphical interface (for end users).
A similar package for graphical user interfaces is the Gadgets system implemented for Oberon System 3. While the Gadgets system is more powerful (e.g. nested objects) it is also more complicated and incompatible with the standard Oberon system. The virtue of the Dialogs package is that it is extremly light-weight and smoothly fits into the existing Oberon system.
Figure 1 shows a sample dialog. Dialogs can be edited interactively and stored on a file. Applications can use dialogs by loading them from a file and retrieving their items by name or by a number. Dialog items can also be connected to commands that are called automatically when the item is clicked. Thus it is very simple to add a graphical user interface to any Oberon program.
Figure 1. A sample dialog
Module Dialog offers commands to use, edit and print a dialog. Dialogs can be displayed in two modes: Dialogs.Open opens a dialog for using it while Dialogs.Edit opens it for editing.
2. Using Dialogs
Opening a Dialog for Using its Items
Dialog.Open (name | ^) opens a dialog viewer and displays the dialog from file name. The menu text of the opened viewer is taken from the file Dialog.Menu.Text if such a file exists.
The user can now work with the dialog by clicking at buttons or check boxes or by typing text into a text field. He cannot modify the dialog, i. e., he cannot add or move dialog items. To do that he has to use the command Dialog.Edit.
Opening a Dialog for Editing
Dialog.Edit (name | ^) opens a dialog viewer and displays the dialog from file name for editing. If such a file does not exist, a new dialog is created.
The following sections describe how to build dialogs by inserting items, moving and resizing them, and inspecting and modifying their attributes. Most editing operations can be done by moving and clicking the mouse. Thus clicking the left button while editing a dialog, causes a cross to appear. This is called the caret.
Inserting New Dialog Items
Dialog items (buttons, check boxes, etc.) can be inserted in viewers opened with Dialog.Edit. Every dialog item is defined in a separate module that exports also a command Insert, to insert an item of this class in the panel containing the caret position.
The syntax of the Insert command is
<itemModule>.Insert ([name] [x y w h] | ^)
where name is a panel-wide unique name, x and y are the lower left coordinates, w is the width and h is the heigth of the object. if these parameters are not set, standard values will be taken. Usually no item can overlap others.
The following items are currently implemented:
DialogButtons. A button is a small named rectangle that can be pushed with an mouse click.
DialogCheckBoxes. A check box is a rectangular button that can be in two states, on and off, toggled with a mouse click. Usally there is a static text displayed to its right.
DialogStaticTexts. A static text item is a text that is shown in a panel but cannot be edited.
DialogTexts. A text item is a rectangle in which the user can enter text.
DialogGroupBoxes. A group box groups together several objects. Of course a group box may overlap other elements.
DialogRadioButtons. A radio button is a diamond object with a state that can be on or off. All radio buttons within a group box are related and represent mutually exclusive choices (i.e., only one button of this set is on at any time).
DialogListBoxes. A list box displays a text of lines, that can be selected by moving the mouse up and down.
DialogComboBoxes. A combo box is an item containing an entry field and a push button. It responds to a mouse click on the push button by showing a text of lines that can be selected by moving the mouse up and down.
DialogSliders. A slider item consists of a rectangular area with a small bar inside. It is used to enter integer numbers.
DialogIntegerSliders. An integer slider item consists of a rectangular area with an integer number inside.
DialogLines. A line item is a graphical object, which can be used to draw a line in the panel.
DialogCircles. A circular item which may overlap other elements.
DialogRectangles. A rectangular item which may overlap other elements.
DialogDates. A date item displays the current date.
DialogClocks. A (digital) clock is an item displaying the current time.
DialogAnalogClock. An analog clock displaying the current time.
DialogColorPicker. A color picker item is a rectangular item, which allows the user to select on of the sixteen Oberon colors.
DialogGraphics. Graphic items support incorporation of graphs compatible with the standard Draw package into dialogs.
Items can also be created using the dialog "Insert.Dlg", which can be opened with Dialog.Open Insert.Dlg (see Figure 2).
Figure 2. Insert.Dlg
Selecting an item of the list box inserts a new item in the panel containing the caret. There are also several text items which allow the user to specify parameters for the new items. If these parameters are not set, default values will be taken.
The meaning of the text items are as follow:
Name the panel-wide unique name of the item.
X, Y the lower left corner coordinates of the item in panel-relative coordinates.
W the width of the item.
H the height of the item.
Cmd a command which is called whenever a property of the object is changed.
Par a string containing the names of the text items that should be concatenated to form Oberon.Par.Text.
Cmd and Par are associated by following rule: The command cmd can assume that Oberon.Par.text contains the texts defined through the property par (e.g. if par = "t1 t2" and there is a text item t1 containing the text "name" and also a text item t2 containing the text "text", then the command can assume that Oberon.Par.text contains the text "name text").
Example: To create a dialog that allows you to invoke System.Time via a button you have to do the following:
- type "MyDialog" in the Dialog field and click the "Edit" Button.
- set the caret in the new viewer with a left mouse click.
- type "Time" in the Name field and "System.Time" in the Cmd field.
- select "Button" from the list box.
This will make the following dialog (see Figure 3).
Figure 3. MyDialog
- store it on a file with the command Dialog.Store.
- open it again clicking the "Open" button.
- every click at the "Time" button will now invoke the command System.Time.
Mouse Clicks
ML sets the caret to the position of the mouse pointer.
MR selects all dialog items in the rectangle described with the pressed mouse button.
MM moves the selected elements (or the element under the mouse pointer if no element is selected) while the mouse is moved.
MR + ML deletes the selected items.
MR + MM copies the selected object to the position of the mouse pointer.
MM + ML changes the size of the element under the mouse pointer, while the mouse is moved.
MM + MR opens a dialog to edit the properties of the object under the mouse pointer.
ML + MM copies the selected objects to the mouse pointer.
Storing a Dialog on a File
Dialog.Store stores the dialog under the name appearing in its menu frame.
Printing a Dialog
Dialog.Print server (* | ^ | {name} ~) prints dialogs to a print server named server. If "*" is specified, the dialog in the marked viewer is printed. Otherwise the dialogs specified by the names are printed.
3. Inspecting and Modifying the Attributes of an Item
The attributes of an item can be conveniently inspected and modified by doing an MM+MR click on the item. A new dialog will appear that allows changing the attributes of the inspected item. Alternatively the user may also inspect and modify these attributes using the following commands.
Retrieving Attributes
Dialog.GetInitCmd writes the command of the marked dialog to the log viewer. This cmd will be called by open the dialog with Dialog.Open. It can be used to initaly different items.
Dialog.GetCmd writes the command of the object under the caret to the log viewer.
Dialog.GetPar writes the parameter of the object under the caret to the log viewer.
Dialog.GetDim writes the coordinates of the lower left corner, the width and the height of the object under the caret to the log viewer
Dialog.GetName writes the name of the object under the caret to the log viewer.
Changing the Attributes of an Item
Dialog.SetInitCmd (cmd | ^) sets the command of the marked dialog to cmd.
Dialog.SetCmd (cmd | ^) sets the command of the object under the caret to cmd.
DialogSetPar (par | ^) sets the parameter of the object under the caret to par.
Dialog.SetDim (x y w h | ^) sets the lower left corner coordinates of the object under the caret to x and y, the width to w, and the height to h.
Dialog.SetName (name | ^) sets the name of the object under the caret to name.
Dialog.AlignSelected (dir | ^) aligns the selected objects so that they have the same left, right, top or bottom coordinates (specified by dir = R(ight), L(eft), U(p) or D(own)).
Dialog.RegulateDistance (dir | ^) regulates the distance between the selected objects.
Dialog.SetGrid (int| ^) sets the grid to which mouse movements are restricted.
4. A very simple Dialog
Dialogs can be used as a graphical user interface for existing Oberon applications. This is shown in Fig. 4. Lets assume a dialog "Open.Dlg" that contains a text named "file" and a button named "Open". The button is associated with the command Edit.Open. The button property par (see above) is set to "file".
Figure 4. Open.Dlg.
The user can open the dialog with Dialog.Open Open.Dlg and can write a file-name in the text item. Pressing the "Open"-button opens the specified file.
5. Retrieving Dialog Items from a Program
Dialog items can be retrieved by name. A dialog panel p can be opened by DialogFrames.OpenPanel(..., p). The item with the name "n" can then be retrieved with item : = p.NamedObject ("n").
The following example shows how to use dialogs from a program. Lets assume a dialog "Test.Dlg" (see Fig. 5) that contains a text named "file", a check box named "draft", and a button named "Do". The button is associated with a command MyEdit.Print. Thus clicking the button calls this command which prints the file specified by the "file" in the mode specified by the check box "draft" (draft mode or normal mode).
Dialogs can also be used as elements in a text (subclass of Texts.Element). The command DialogElems.Insert inserts a new dialog element into a text at the text caret position. Using the middle mouse button, a dialog element can be "opened" for editing in a dialog viewer. The command DialogElems.Update in the viewer
s menu can be used to make the modifications in the dialog permanent. Dialog elements can be used like ordinary dialogs: focus the element using the left mouse key and do everything what you would do with an ordinary dialog.
command explicit parameters implicit parameters
DialogElems.Insert ("^" | "*" | name) caret (plus marked viewer, if "*" is used)
Inserts a dialog element sized to show the dialog stored in file "name". If a dialog viewer is marked, the command inserts the dialog of this viewer.
Comments
Error reports and comments may be sent to knasmueller@ssw.uni-linz.ac.at or oberon@ssw.uni-linz.ac.at
(.txt)